Cómo compilar un dispositivo Matter

1. Introducción

Matter es un protocolo de conectividad que ofrece oportunidades emocionantes para el desarrollo de dispositivos inteligentes. En este codelab, compilarás tu primer dispositivo Matter. Para obtener más información sobre Matter, visita el Developer Center 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 encargar y controlar tu dispositivo Matter con Google Home

Qué necesitarás

2. Configure su 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 panel de desarrolladores.

  1. Conecta la placa para desarrolladores a la computadora con un cable USB.
  2. Busca en el sistema de archivos /dev para encontrar el dispositivo de la placa del desarrollador. Para limitar la búsqueda, especifica el prefijo de dispositivo de la placa del desarrollador. 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 vas a usar en este codelab.

Cómo configurar 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 se indica a continuación.

Instala dependencias

Ejecuta el siguiente comando para instalar los objetos binarios del paquete de Linux que quizás 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 Espressif IoT Development Framework o “ESP-IDF”).

  1. Crea un directorio que contenga 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 puedes administrar tus integraciones de Matter con Google Home.

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

Cómo crear un proyecto de desarrollador

En primer lugar, ve a la consola para desarrolladores de Google Home:

  1. En la página Administrar proyectos, haz clic en Crear un proyecto.
    Developer Center de Google Home
  2. En la página Comenzar, haz clic en Crear proyecto.

  1. Ingresa un nombre de proyecto único y, luego, haz clic en Crear proyecto nuevo. Diálogo de creación de proyecto nuevo
  2. Haz clic en + Add integration, que te llevará a la pantalla “Recursos de Matter”, en la que podrás ver la documentación de desarrollo de Matter y leer sobre algunas herramientas.
  3. Cuando estés listo para continuar, haz clic en Next: Develop, que muestra la página de la lista de tareas de Matter.
  4. Haz clic en Siguiente: Configuración.
  5. En la página Configuración, ingresa el Nombre del producto.
  6. Haz clic en Select device type y selecciona el tipo de dispositivo en el menú desplegable (en este caso, Light).
  7. En el ID del proveedor (VID), selecciona Test VID y elige 0xFFF1 en el menú desplegable Test VID. En ID del producto (PID), ingresa 0x8000, haz clic en Guardar y continuar (Save & continue) y, luego, en Guardar (Save) en la siguiente página.
    Configura un proyecto
  8. Ahora verás un dispositivo Matter en Integraciones de Matter. Integraciones de Matter
  9. Reinicia tu concentrador para asegurarte de que reciba la configuración más reciente del proyecto de integración de Matter. Si tienes que cambiar el VID o PID más adelante, también deberás reiniciar el dispositivo después de guardar el proyecto para que se aplique el cambio. 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 encuentran en la carpeta de ejemplos del repositorio de GitHub. Hay varios ejemplos disponibles, pero nuestro enfoque en este codelab es la lighting-app.

Este ejemplo es un dispositivo simple que aparece en Google Home como una luz de encendido y 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 del ESP32 lighting-app y configura 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 flecha hacia la izquierda para volver al menú de nivel superior.
    4. Seleccione Component config --->.
    5. Seleccione CHIP Device Layer --->.
    6. Seleccione Device Identification Options --->.
    7. Establece Vendor ID en el VID asignado por la Alianza o en un VID de prueba.
    8. Establece Product ID en el PID que estableciste en la integración de Matter en la consola para desarrolladores de Google Home.
    9. Presiona S para guardar.
    10. Presione Intro para aceptar la ruta de archivo predeterminada en la que se guardará la configuración.
    11. Presiona Intro 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 se debería completar sin errores.

Programa el dispositivo

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

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

5. Conéctate al dispositivo

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

6. Solicita 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 poner tu dispositivo en la estructura Matter. Este es un dispositivo Google Nest, como el Nest Hub (2a generación), que es compatible con Matter y que funciona como router de borde para dispositivos compatibles con Thread y como ruta de entrega local para enrutar intents de casa inteligente.

Consulta esta lista para ver qué concentradores son compatibles con Matter.

Antes de comenzar el proceso de comisión, asegúrate de que se cumpla lo siguiente:

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

Vincula el dispositivo

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

Nota: Si utilizas un dispositivo M5STACK, ten en cuenta que la pantalla permanecerá en blanco después de la instalación, por lo que tendrás que ver el código QR con la URL que aparece en la consola. También puedes escribir 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

La comisión falla

Para obtener más sugerencias sobre cómo solucionar problemas, consulta la página de solución de problemas de Matter.

7. Cómo controlar el dispositivo

Una vez que tu dispositivo compatible con Matter se ponga en marcha correctamente y aparezca en la app de Google Home como una bombilla, puedes intentar controlarlo con 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 Asistente de Google en tu teléfono o concentrador para activar o desactivar el estado del dispositivo a partir de comandos por voz, como decir "Hey Google, enciende las luces".

Para ver más ejemplos de comandos, consulta la sección Cómo controlar los dispositivos de casa inteligente con comandos por voz de Cómo controlar los dispositivos de casa inteligente que se agregaron a la app de Google Home.

App de Google Home

Puedes presionar las etiquetas Activar y Desactivar junto al ícono de la 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 de Asistente de Google

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

8. Felicitaciones

Creaste y pusiste en marcha correctamente tu primer dispositivo Matter. ¡Genial!

En este codelab aprendiste a hacer lo siguiente:

  • Instalar un entorno de desarrollo de Matter desde los requisitos hasta un estado de trabajo
  • Compila y ejecuta un dispositivo Matter.
  • Comisión y controla tu dispositivo desde Google Home.

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