Cómo compilar un dispositivo Matter

1. Introducción

Matter es un protocolo de conectividad que ofrece oportunidades interesantes para el desarrollo de dispositivos inteligentes. En este codelab, compilarás tu primer dispositivo Matter. Para obtener información sobre Matter, visita el Centro para desarrolladores de Google Home: Matter o el sitio web de Connectivity Standards Alliance.

Qué aprenderás

  • Cómo integrar un dispositivo físico con Matter
  • Cómo acondicionar y controlar tu dispositivo Matter con Google Home

Requisitos

2. Configura tu entorno

Identifica el dispositivo en serie

El primer paso para configurar tu entorno de desarrollo es determinar a qué puerto en serie está conectado tu dispositivo. Esta información te permitirá programar e interactuar con tu placa de desarrollo.

  1. Conecta la placa de desarrollo a la computadora con un cable USB.
  2. Busca en el sistema de archivos /dev para encontrar el dispositivo de la placa de desarrollo. Puedes acotar la búsqueda si especificas el prefijo del dispositivo de la placa de desarrollo. El ESP32 de Espressif usa /dev/ttyUSBx:
    user@host $ ls /dev/ttyUSB*
/dev/ttyUSB0

Configura tu concentrador

Configura tu concentrador con la misma Cuenta de Google que piensas usar para este codelab.

Configura tu entorno de desarrollo

Requisitos previos

Estas instrucciones se probaron en Debian Linux y deberían funcionar en la mayoría de las distribuciones de Linux basadas en Debian, incluido Ubuntu. Si trabajas con una distribución de Linux diferente, el procedimiento de configuración de dependencias puede variar de lo que sigue.

Instala dependencias

Ejecuta el siguiente comando para instalar los archivos binarios de paquetes de Linux requeridos que aún no estén instalados:

$ sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev screen

Configura el SDK

Para continuar con este codelab, necesitarás el SDK de Espressif (el framework de desarrollo de IoT de Espressif o "ESP-IDF").

  1. Crea un directorio para contener el ESP-IDF:
    $ mkdir ~/esp-idf_tools
  2. Clona el ESP-IDF de GitHub en este directorio:
    $ cd ~/esp-idf_tools
$ git clone -b v4.4.3 --recursive https://github.com/espressif/esp-idf.git
  3. Completa la instalación de la cadena de herramientas:
    $ cd ./esp-idf
$ ./install.sh
$ cd ~/

Configura el SDK de Matter

  1. Clona el repositorio de Matter de código abierto:
    $ git clone https://github.com/project-chip/connectedhomeip.git
$ cd ./connectedhomeip
$ git fetch origin v1.0-branch
$ git checkout FETCH_HEAD
  2. Recupera los submódulos del repositorio:
    $ ./scripts/checkout_submodules.py --shallow --platform esp32
  3. Inicia el entorno de desarrollo de Matter:
    $ source ./scripts/bootstrap.sh

3. Consola para desarrolladores de Google Home

La consola para desarrolladores de Google Home es la aplicación web en la que administras tus integraciones de Matter con Google Home.

Cualquier dispositivo Matter que haya aprobado la certificación de Matter de Connectivity Standards Alliance (Alliance) funciona en el ecosistema de Google Home. Los dispositivos en desarrollo que no se hayan certificado se pueden acondicionar en el ecosistema de Google Home en ciertas condiciones. Consulta Restricciones de vinculación para obtener más información.

Crea un proyecto de desarrollador

Para comenzar, ve a la consola para desarrolladores de Google Home:

  1. Haz clic en Crear proyecto.
  2. Ingresa un nombre de proyecto único y, luego, haz clic en Crear proyecto. Diálogo de creación de proyecto nuevo
  3. Haz clic en + Agregar integración, que te lleva a la pantalla Recursos de Matter, donde puedes ver la documentación de desarrollo de Matter y leer sobre algunas herramientas.
  4. Cuando estés listo para continuar, haz clic en Siguiente: Desarrollar, que muestra la página Lista de tareas de Matter.
  5. Haz clic en Siguiente: Configuración.
  6. En la página Configuración, ingresa el Nombre del producto.
  7. Haz clic en Seleccionar tipo de dispositivo y selecciona el tipo de dispositivo en el menú desplegable (en este caso, Light).
  8. En ID de proveedor (VID), selecciona VID de prueba y elige 0xFFF1 en el menú desplegable VID de prueba. En ID de producto (PID), ingresa 0x8000 y haz clic en Guardar y continuar y, luego, en Guardar en la página siguiente. Usa estos valores exactos de VID/PID, ya que los pasos posteriores del codelab dependen de ellos.
    Configura un proyecto
  9. Ahora verás tu integración en Integraciones de Matter.
  10. Reinicia tu concentrador para asegurarte de que reciba la configuración más reciente del proyecto de integración de Matter. Si debes cambiar el VID o el PID más adelante, también deberás reiniciar después de guardar el proyecto para que el cambio se aplique. Consulta Cómo reiniciar los dispositivos Google Nest o Google Wifi para obtener instrucciones de reinicio paso a paso.

4. Compila el dispositivo

Todos los ejemplos de Matter se colocan en la carpeta examples del repositorio de GitHub. Hay varias muestras disponibles, pero nuestro enfoque en este codelab es en el lighting-app.

Este ejemplo es un dispositivo simple que aparece en Google Home como una luz de encendido/apagado, que responde a los comandos de encendido y apagado. Hacer que controle una luz eléctrica real está fuera del alcance de este codelab.

Configura la compilación

  1. Configura el SDK de Matter y activa el entorno de compilación de Matter:
    $ cd ~/esp-idf_tools/esp-idf
$ source export.sh
$ cd ~/connectedhomeip
$ source ./scripts/activate.sh
  2. Habilita Ccache, que acelera el proceso de compilación:
    $ export IDF_CCACHE_ENABLE=1
  3. Ve al directorio de compilación de ESP32 lighting-app y establece la arquitectura de destino:
    $ cd ./examples/lighting-app/esp32
$ idf.py set-target esp32
    1. Ejecuta la utilidad de configuración:
      $ idf.py menuconfig
    2. Selecciona Demo -> Device Type y establece Device Type en ESP32-DevKitC.
    3. Presiona la tecla de flecha izquierda para volver al menú de nivel superior.
    4. Selecciona Component config --->.
    5. Selecciona CHIP Device Layer --->.
    6. Selecciona Device Identification Options --->.
    7. Establece Vendor ID en el VID asignado por Alliance o en un VID de prueba.
    8. Establece Product ID en el PID que configuraste en la integración de Matter en la consola para desarrolladores de Google Home.
    9. Presiona S para guardar.
    10. Presiona Return para aceptar la ruta de acceso predeterminada en la que se guardará la configuración.
    11. Presiona Return para descartar el diálogo de confirmación de guardado.
    12. Presiona Q para salir de la utilidad de configuración.

Ejecuta la compilación

Invoca la secuencia de comandos de compilación:

idf.py build

La compilación debería completarse sin errores.

Programa el dispositivo

  1. Conecta la placa de desarrollo a la computadora con un cable USB.
  2. Borra cualquier firmware anterior del dispositivo (si solo tienes una placa de desarrollo conectada a tu computadora, puedes omitir la opción -p {device}. El dispositivo debería detectarse automáticamente):
    idf.py -p {device} erase-flash
  3. Copia tu nueva aplicación en la placa de desarrollo con:
    idf.py -p {device} flash

Puedes encontrar más información sobre las opciones de parpadeo en la página de documentación Espressif esptool.py.

5. Conéctate al dispositivo

  1. Abre una ventana de terminal.
  2. Toma nota del directorio en el que te encuentras y, luego, conéctate a tu nuevo dispositivo Matter con GNU screen:
    $ screen -L {device} 115200
  3. Si ves una consola en blanco, presiona el botón RESET para iniciar el proceso de arranque del dispositivo.

6. Acondiciona el dispositivo

Nota: Este paso solo se realizará correctamente si ya configuraste tu proyecto en la consola para desarrolladores de Google Home.

Nest Hub

Se requiere un concentrador para acondicionar tu dispositivo en la estructura de Matter. Este es un dispositivo Google Nest, como el Nest Hub (2ª gen.), que admite Matter y que servirá como un router de borde para dispositivos habilitados para Thread y como una ruta de acceso de fulfillment local para enrutar intents de casa inteligente.

Consulta esta lista para ver qué concentradores admiten Matter.

Antes de comenzar el proceso de acondicionamiento, verifica lo siguiente:

  • Tu concentrador está vinculado con la misma Cuenta de Google que usaste para acceder a Google Home Console.
  • Tu concentrador está en la misma red Wi-Fi que la computadora que usas para ejecutar tu dispositivo Matter virtual.
  • Tu concentrador está en la misma estructura que usas en la app de Google Home. (La "casa" en el Google Home Graph representa tu estructura).

Vincula el dispositivo

Sigue las instrucciones de vinculación de ESP32 para vincular tu dispositivo.

Nota: Si usas un M5STACK, ten en cuenta que su pantalla permanecerá en blanco después de que se flashee, por lo que deberás ver el código QR con la URL que aparece en la consola. O bien, puedes ingresar el código de vinculación manual.

Ejemplo de resultado de la consola que muestra la URL del código QR:

I (1926) chip[DL]: Done driving station state, nothing else to do...
I (1936) chip[SVR]: SetupQRCode: [MT:X.XXXXXXXXXXXXXXXXX]
I (1936) chip[SVR]: Copy/paste the below URL in a browser to see the QR Code:
I (1946) chip[SVR]: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3XX.KXXXXXXXXXXXXXXXX
I (1956) chip[SVR]: Manual pairing code: [XXXXXXXXXXX]]

Solución de problemas

Falla el acondicionamiento

Para obtener más sugerencias de solución de problemas, consulta la página Solución de problemas de Matter.

7. Controla el dispositivo

Una vez que tu dispositivo compatible con Matter se acondicione correctamente y aparezca en la app de Google Home como una bombilla, puedes intentar controlarlo con el Asistente de Google, la app de Google Home o el simulador del Asistente de Google en la extensión de Google Home para VS Code.

Asistente de Google

Usa el Asistente de Google en tu teléfono o concentrador para activar o desactivar el estado del dispositivo con comandos de voz, como "Hey Google, activa o desactiva mis luces".

Consulta la sección Controla dispositivos inteligentes para la casa con comandos de voz de Cómo controlar los dispositivos de casa inteligente que se hayan agregado a la app de Google Home para obtener más ejemplos de comandos.

App de Google Home

Puedes presionar las etiquetas On y Off junto al ícono de bombilla que se muestra en la app de Google Home.

Consulta Cómo controlar dispositivos con la app de Google Home para obtener más información.

Simulador del Asistente de Google

En la extensión de Google Home para VS Code, con el simulador del Asistente de Google, puedes emitir expresiones a tu dispositivo con una interfaz similar a un chat.

8. ¡Felicitaciones!

Creaste y acondicionaste correctamente tu primer dispositivo Matter. Excelente.

En este codelab aprendiste a hacer lo siguiente:

  • Instalar un entorno de desarrollo de Matter desde los requisitos hasta un estado de funcionamiento
  • Compilar y ejecutar un dispositivo Matter
  • Acondicionar y controlar tu dispositivo desde Google Home

Para obtener más información sobre Matter, explora estas referencias:

  • El Matter Primer de Google Home, donde aprenderás los conceptos y principios importantes del protocolo Matter
  • La especificación de Matter, la biblioteca de dispositivos Matter y la biblioteca de clústeres de aplicaciones Matter, publicadas por la Connected Standard Alliance
  • El repositorio de GitHub de Matter.