Cómo compilar un dispositivo virtual 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 con recursos del SDK de Matter.

Para obtener información sobre Matter, visita el Centro para desarrolladores de Google Home o el sitio web de Connectivity Standards Alliance.

Qué aprenderás

  • Cómo configurar un entorno de compilación de Matter
  • Cómo compilar un dispositivo Matter virtual que se ejecuta en tu computadora
  • Cómo poner en servicio y controlar el dispositivo Matter virtual con Google Home

Requisitos

  • Una unidad central, que es cualquier dispositivo Google Nest que admita Matter, como el Nest Hub (2ª gen.).
  • Una máquina Linux que ejecute el sistema de ventanas X11.
  • Docker.
  • Git
  • Conocimientos básicos de Linux
    • Ten en cuenta que el shell supuesto para todos los comandos de este codelab es BASH.

2. Configura tu entorno

Revisa tu hardware

Esta instalación de Docker no es compatible con computadoras Windows ni macOS. Puedes instalar y compilar Matter de forma manual en macOS.

Además, en estas instrucciones, se supone que tu máquina Linux ejecuta el sistema de ventanas X11. Si tu máquina Linux ejecuta Wayland, asegúrate de que también esté instalado X.Org.

Cómo configurar el entorno de desarrollo

  1. Instala Docker Engine (no uses Docker Desktop).
  2. Clona el SDK de Matter y toma nota de la confirmación que usaremos a continuación.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Ejecuta un contenedor de compilación con las imágenes públicas de CI del SDK y ejecuta el dispositivo virtual recién compilado desde este contenedor. Busca la imagen que se usará para que coincida con nuestra versión del SDK de la siguiente manera:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Si usas la misma confirmación, deberías ver ghcr.io/project-chip/chip-build:66Primero, reenvía los puertos xhost para que podamos usar las aplicaciones de la IU más adelante:
    xhost local:1000
    Luego, inicia el contenedor con los recursos adecuados reenviados desde el host (nuestra confirmación del SDK, las herramientas de redes y los recursos de visualización o comunicación).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

Comprendamos el comando de Docker y las opciones que le pasamos:

  • xhost local:1000 permite que el sistema X Window reciba conexiones del host local en el puerto 1000, lo que permite usar una interfaz gráfica de usuario.
  • docker run … image ejecuta la imagen determinada y la extrae del registro de Docker si es necesario.
  • --ipc=host permite que Docker comparta el espacio de nombres de comunicación entre procesos con tu máquina anfitrión.
  • --net=host permite que Docker use la pila de red del host dentro del contenedor, lo que es necesario para que pase el tráfico mDNS del host al contenedor y para compartir la pantalla X11 del host.
  • -e DISPLAY exporta $DISPLAY al host, lo que proporciona acceso a la interfaz gráfica del sistema. Esto es necesario para ejecutar la herramienta ZAP cuando se editan clústeres de Matter.
  • -it ejecuta Docker con una terminal interactiva (tty), en lugar de como un proceso en segundo plano.
  • --mount activa el SDK que verificamos anteriormente en el contenedor.
  • --workdir establece el directorio de trabajo en el inicio en nuestro directorio del SDK activado.

De manera opcional, puedes ejecutar una segunda instancia de sesión de terminal:

user@host> docker exec -it matter-container /bin/bash
$

Detén e inicia el contenedor de Docker de Matter

Cada vez que ejecutes un comando docker run, crearás un contenedor nuevo con la imagen especificada. Cuando lo hagas, se perderán tus datos antiguos, que se guardaron en una instancia de contenedor anterior. A veces, esto es lo que quieres que suceda, ya que te permite comenzar con una instalación nueva. Sin embargo, hay ocasiones en las que prefieres guardar tu trabajo y la configuración del entorno entre sesiones.

Por este motivo, después de crear el contenedor, puedes detenerlo para evitar perder tu trabajo.

user@host> docker stop matter-container

Cuando estés listo para volver a ejecutarlo, inicia el contenedor y abre una ventana de terminal:

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

Puedes abrir sesiones de terminal adicionales en tu contenedor con lo siguiente:

user@host> docker exec -it matter-container /bin/bash

O inicia una sesión raíz con lo siguiente:

user@host> docker exec -u 0 -it matter-container /bin/bash

Configuración inicial de Matter

Inicializa el SDK

Inicializa el SDK de Matter. Esta operación tardará varios minutos en completarse.

source scripts/bootstrap.sh
python3 scripts/checkout_submodules.py --shallow --platform linux

Ahora se inicializó tu SDK de Matter. Para volver a inicializar el entorno rápidamente en el futuro, ejecuta lo siguiente:

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

Comparte archivos entre el host y el contenedor

Anteriormente, accedimos a los archivos de tu máquina anfitrión desde el contenedor con una activación de vinculación. También puedes escribir archivos en el directorio activado desde el contenedor para acceder desde el host.

En general, usa activaciones de vinculación ejecutando tu contenedor con el argumento adicional --mount source=$(pwd),target=/workspace,type=bind para activar tu directorio de trabajo actual en el contenedor en /workspace.

user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

Los permisos del usuario del contenedor en el directorio activado se deben administrar en el host.

Obtén el ID de grupo del usuario del contenedor desde el contenedor.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

Abre otra sesión de terminal en el host del contenedor y establece el directorio de trabajo en el directorio activado por el contenedor.

Establece de forma recursiva el grupo para los archivos en el directorio activado en el grupo del usuario del contenedor.

user@host> sudo chgrp -R 1000 .

Otorga los permisos deseados en el directorio al grupo. En este ejemplo, se otorgan al grupo del usuario del contenedor permisos de lectura, escritura y ejecución en todos los archivos del directorio activado.

user@host> sudo chmod -R g+rwx .

Ten en cuenta que estos comandos no afectan el permiso de los archivos nuevos creados por el usuario host. Recuerda actualizar los permisos de los archivos nuevos creados en el host según sea necesario.

Puedes agregar tu usuario host al grupo del usuario del contenedor para heredar permisos en los archivos creados por el usuario del contenedor.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

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 certificaron se pueden poner en servicio 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 Vendor ID (VID), selecciona Test VID y elige 0xFFF1 en el menú desplegable Test VID. En Product ID (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 unidad central 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 paso a paso sobre el reinicio.

4. Compila un dispositivo

Todos los ejemplos de Matter se encuentran en la carpeta examples del repositorio de GitHub. Hay varias muestras disponibles, pero en este codelab nos centraremos en Chef.

Chef es lo siguiente:

  • Una app de ejemplo que proporciona una interfaz de terminal y que incluye funciones que también se encuentran en la app examples/shell
  • Una secuencia de comandos que adopta el principio de convención sobre configuración para encapsular varias de las tareas comunes necesarias para desarrollar un dispositivo compatible con Matter

Navega a la carpeta de ejemplo de Chef y realiza tu primera compilación de Matter:

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

Chef tiene algunas opciones que se pueden ver ejecutando chef.py -h. Las opciones que usamos aquí son las siguientes:

  • -d: Define el tipo de dispositivo que se usará. En este caso, creamos una app de iluminación con controles de encendido/apagado y de nivel.
  • -z: Invoca la herramienta ZAP para generar los archivos fuente que implementan el tipo de dispositivo. Es decir, según tu elección de iluminación, ZAP creará automáticamente el código que se incorporará a la compilación que define la luz (el modelo de datos) y cómo interactúa con otros dispositivos (el modelo de interacción).
  • -b: Compilaciones.
  • -r: [Opcional] Habilita el servidor RPC en el dispositivo Matter virtual para que otros componentes (como la GUI) puedan comunicarse con el dispositivo para configurar y recuperar atributos del modelo de datos.
  • -t linux: Plataforma de destino. Las plataformas compatibles son linux, nrfconnect y esp32. Puedes ejecutar ./chef.py -h para ver todos los comandos disponibles y las plataformas de destino compatibles. linux se usa para dispositivos Matter virtuales.

Ejecuta el dispositivo

Matter usa el puerto TCP/UDP 5540, por lo que, si tienes un firewall ejecutándose en tu computadora, apágalo o permite las conexiones TCP/UDP entrantes en el puerto 5540.

Ejecuta el dispositivo virtual en el contenedor con lo siguiente:

$ ./linux/out/rootnode_dimmablelight_bCwGYSDpoe
   [1648589956496] [14264:16538181] CHIP: [DL] _Init]
...
[1648562026.946882][433632:433632] CHIP:SVR: SetupQRCode: [MT:Y3.13Y2N00KA0648G00]
[1648562026.946893][433632:433632] CHIP:SVR: Copy/paste the below URL in a browser to see the QR Code:
[1648562026.946901][433632:433632] CHIP:SVR: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

Deja el dispositivo en ejecución. Ahora, centraremos nuestra atención en la app de Google Home para que podamos poner en servicio tu dispositivo en Google Home.

Detén el dispositivo

Si necesitas detener el dispositivo, puedes salir del programa con CTRL + C. Si la app no se cierra, es posible que también debas usar CTRL + \.

Las credenciales de tu dispositivo virtual se almacenan en el directorio /tmp/, en archivos que comienzan con el prefijo chip.

Si quieres repetir todo el proceso de puesta en servicio desde el principio, deberás borrar esos archivos ejecutando el siguiente comando:

$ rm /tmp/chip*

5. Pon en servicio el dispositivo

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

Nest Hub

Se requiere una unidad central para poner en servicio 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 compatibles con Thread y como una ruta de acceso de cumplimiento local para enrutar intents de casa inteligente.

Consulta esta lista para ver qué unidades centrales admiten Matter.

Antes de iniciar el proceso de puesta en servicio, verifica lo siguiente:

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

Obtén un código QR

El proceso de puesta en servicio necesita información de incorporación de Matter que se proporciona a través de un código QR. Examina el resultado de la consola de la aplicación Matter, que contendrá un vínculo al código QR pertinente para la puesta en servicio.

Realiza la operación de puesta en servicio

  1. Abre la app de Google Home.
  2. Presiona + en la esquina superior izquierda.
  3. Presiona Configurar dispositivo.
  4. Presiona Nuevo dispositivo.
  5. Selecciona tu casa y presiona Siguiente.
  6. La app de Google Home busca tu dispositivo. Si aparece el mensaje "Se encontró un dispositivo Matter…", presiona "Sí". De lo contrario, presiona Configurar otro dispositivo y, luego, selecciona Dispositivo Matter en la lista de dispositivos.
  7. Apunta la cámara al código QR de tu dispositivo o al código QR generado por el sitio web.
  8. Continúa con el proceso de vinculación como se indica en el flujo de la app de Google Home.

Una vez que completes estos pasos, el dispositivo Matter virtual debería ponerse en servicio correctamente y debería aparecer como un ícono nuevo en la app de Google Home.

Bombilla vinculada en la app de Google Home

Solución de problemas

La puesta en servicio falla con los mensajes de error "Problema de conectividad" o "No se pudo comunicar con Google"

  • Asegúrate de haber creado un proyecto con la combinación correcta de VID/PID en Google Home Console y de no tener otros proyectos que usen la misma combinación de VID/PID.

La puesta en servicio falla después de "Escanear tu dispositivo" durante un período prolongado

6. Controla el dispositivo

Una vez que tu dispositivo compatible con Matter se ponga en servicio correctamente y aparezca en la app de Google Home como una bombilla, podrás probar el control del dispositivo con diferentes métodos:

  • Con el Asistente de Google
  • Con la app de Google Home

Asistente de Google

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

Consulta la sección Controla dispositivos inteligentes para la casa con comandos por 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 Encendido y Apagado junto al ícono de bombilla que se muestra en la app de Google Home.

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

7. ¡Felicitaciones!

Creaste correctamente tu primer dispositivo Matter. Excelente.

En este codelab aprendiste a hacer lo siguiente:

  • Instalar un entorno de desarrollo de Matter
  • Compilar y ejecutar un dispositivo Matter virtual
  • Poner en servicio y controlar tu dispositivo virtual desde Google Home

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