Compila un dispositivo virtual Matter

1. Introducción

Matter es un protocolo de conectividad que ofrece emocionantes oportunidades para el desarrollo de dispositivos inteligentes. En este codelab, compilarás tu primer dispositivo Matter con recursos del SDK de Matter.

Para obtener más información sobre Matter, visita el Developer Center 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 ejecute en tu computadora
  • Cómo asignar y controlar el dispositivo virtual Matter con Google Home

Requisitos

  • Una unidad central, que es cualquier dispositivo Google Nest compatible con Matter, como el Nest Hub (2a generación)
  • Una máquina de Linux que ejecuta 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 el hardware

Las computadoras Windows y macOS no son compatibles con esta instalación de Docker. Puedes instalar y compilar Matter manualmente 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 X.Org también esté instalado.

Cómo configurar el entorno de desarrollo

  1. Instala Docker Engine (no uses Docker Desktop).
  2. Clona el SDK de Matter, observa la confirmación que usamos en lo siguiente.
    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. Ubica la imagen que quieras usar y 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 luego podamos usar las aplicaciones de la IU:
    xhost local:1000
    A continuación, inicia el contenedor con los recursos adecuados reenviados desde el host (nuestros recursos de confirmación de la compra del SDK, redes y visualización/comunicaciones).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

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

  • xhost local:1000 permite que el sistema de ventanas X 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, que es necesaria para pasar el tráfico mDNS del host al contenedor y compartir la pantalla X11 del host.
  • -e DISPLAY exporta $DISPLAY al host y 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 previamente extrajimos 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, deberás crear 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 deseas que suceda porque te permite comenzar con una instalación nueva. Sin embargo, hay ocasiones en las que preferirías guardar la configuración de tu trabajo y entorno entre sesiones.

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

user@host> docker stop matter-container

Cuando tengas todo listo para volver a realizar la ejecución, 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 el siguiente comando:

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

O inicia una sesión raíz con:

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

Se inicializó tu SDK de Matter. Para reinicializar el entorno rápidamente en el futuro, ejecuta el siguiente comando:

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 mediante 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 vinculaciones ejecutando el contenedor con el argumento adicional --mount source=$(pwd),target=/workspace,type=bind para activar el 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 del grupo del usuario contenedor desde el contenedor.

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

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

Establece de manera recurrente el grupo de archivos del directorio activado en el grupo del usuario del contenedor.

user@host> sudo chgrp -R 1000 .

Otorga al grupo los permisos que desees en el directorio. En este ejemplo, se otorgan permisos de lectura, escritura y ejecución al grupo del usuario del contenedor 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 que crea el usuario del 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 los permisos en los archivos que creó 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.

Todos los dispositivos Matter que hayan aprobado la certificación Matter de Connectivity Standards Alliance (Alliance) funciona en el ecosistema de Google Home. Los dispositivos en desarrollo que no están certificados se pueden encargar en el ecosistema de Google Home bajo ciertas condiciones. Consulta Restricciones de sincronización para obtener más información.

Crea un proyecto de desarrollador

Primero, 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 Crear proyecto nuevo
  3. Haz clic en + Add integration para ir a la pantalla Matter resources, en la que podrás ver la documentación de desarrollo de Matter y leer sobre algunas herramientas.
  4. Cuando tengas todo listo para continuar, haz clic en Next: Develop, que mostrará la página de la lista de tareas de Matter.
  5. Haz clic en Next: Setup.
  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 del proveedor (VID), selecciona VID de prueba y selecciona 0xFFF1 en el menú desplegable VID de prueba. En ID del producto (PID), ingresa 0x8000 y haz clic en Guardar y continuar y, luego, hacer clic en Guardar en la siguiente página. Usa estos valores exactos de VID/PID; los pasos posteriores del codelab dependen de ellos.
    Configura un proyecto
  9. Ahora verás tu integración en Integraciones de Matter.
  10. Reinicia la unidad para asegurarte de que reciba la configuración del proyecto de integración de Matter más reciente. Si tienes que cambiar el VID o PID más adelante, también deberás reiniciar 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. Cómo compilar un dispositivo

Todos los ejemplos de Matter se encuentran en la carpeta examples del repositorio de GitHub. Hay varios ejemplos disponibles, pero nuestro enfoque en este codelab es Chef.

Chef es lo siguiente:

  • Una app de ejemplo que proporciona una interfaz de terminal y une funciones que también se encuentran en la app de 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 si ejecuta chef.py -h. Estas son las opciones que usamos:

  • -d: Define el tipo de dispositivo que se usará. En este caso, crearemos una app de iluminación con controles de encendido y apagado y niveles.
  • -z: Invoca la herramienta ZAP para generar los archivos de origen que implementan el tipo de dispositivo. Es decir, en función de tu elección de iluminación, ZAP creará automáticamente código para incorporarlo a la compilación que define la luz (el modelo de datos) y cómo esta interactúa con otros dispositivos (el modelo de interacción).
  • -b: compilaciones.
  • -r: [opcional] habilita el servidor de RPC en el dispositivo virtual Matter para que otros componentes (como la GUI) puedan comunicarse con el dispositivo para establecer y recuperar atributos del modelo de datos.
  • -t linux: Es la plataforma de destino. Las plataformas de compatibilidad 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 virtuales Matter.

Ejecuta el dispositivo

Matter usa el puerto TCP/UDP 5540, por lo que, si tienes un firewall en ejecución en la 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 funcionamiento. Ahora dirigimos nuestra atención a la app de Google Home para que podamos enviar tu dispositivo a la app de Google Home.

Detén el dispositivo

Si necesitas detener el dispositivo, cierra el programa con Ctrl + C. Si la aplicación 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 comisión desde el principio, deberás ejecutar el siguiente comando para borrar esos archivos:

$ rm /tmp/chip*

5. Encargar 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 una unidad central para enviar tu dispositivo a la tela de Matter. Este es un dispositivo Google Nest, como Nest Hub (2a generación), que admite Matter y que servirá 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é unidades centrales admiten Matter.

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

  • La unidad central está sincronizada con la misma Cuenta de Google que usaste para acceder en la consola de Google Home.
  • La unidad central está conectada a la misma red Wi-Fi que la computadora que usas para ejecutar el dispositivo Virtual Matter.
  • La unidad central está en la misma estructura que usas en la app de Google Home. (La "casa" en Google Home Graph representa tu estructura).

Obtener un código QR

El proceso de comisión debe proporcionar la información de integración de Matter a través de un código QR. Examina el resultado de la consola de la aplicación de Matter que contendrá un vínculo al código QR relevante para la comisión.

Realiza la operación de comisión

  1. Abre la app de Google Home.
  2. Presiona el signo + que aparece 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 hayas completado estos pasos, el dispositivo virtual Matter se debería poner en marcha correctamente y debería aparecer como un nuevo ícono en la app de Google Home.

Bombilla vinculada en la app de Google Home

Soluciona problemas

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

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

La puesta en servicio falla después de "Escanear el dispositivo" durante mucho tiempo

6. Cómo controlar el dispositivo

Una vez que el dispositivo compatible con Matter se haya encargado correctamente y aparezca en la app de Google Home como una bombilla, puedes probar el control del dispositivo con diferentes métodos:

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

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, activa o desactiva las luces".

Para obtener más ejemplos de comandos, consulta la sección Cómo controlar dispositivos de casa inteligente con comandos por voz en Cómo controlar los dispositivos de casa inteligente agregados 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.

Para obtener más información, consulta la sección Cómo controlar dispositivos con la app de Google Home en Cómo controlar los dispositivos de casa inteligente que se agregaron a la app de Google Home.

7. ¡Felicitaciones!

Creaste correctamente tu primer dispositivo Matter. ¡Genial!

En este codelab aprendiste a hacer lo siguiente:

  • Instalar un entorno de desarrollo de Matter.
  • Crear y ejecutar un dispositivo virtual de Matter
  • Envía y controla tu dispositivo virtual desde Google Home.

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